COISPA Website 
COISPA Github Example ALADYM configuration file.ALADYM_tuning_tutorial
Introduction
The tuning module described here is a targeted extension of BEMTOOL and operates exclusively on the ALADYM biological component. It does not modify, calibrate, or optimise any economic, effort-allocation, or management modules of BEMTOOL. Its sole purpose is to automate the calibration of selected ALADYM input parameters against external stock-assessment outputs.
Specifically, the tuning workflow:
runs ALADYM repeatedly using predefined configuration files,
varies a controlled subset of biological parameters (e.g. Tr, Fbar range, and separately the selectivity parameters),
evaluates model outputs against assessment-derived time series,
identifies parameter combinations that minimise a predefined error metric.
This procedure replaces manual, GUI-driven trial-and-error calibration with a deterministic, script-driven process that is fully reproducible and traceable.
The tuning framework is designed to be used after a standard BEMTOOL/ALADYM setup is already functional. It assumes that:
ALADYM runs correctly for a single configuration,
input data are internally consistent,
assessment outputs (SSB, Fbar, catches) are available as reference series.
This tuning module is not a replacement for the standard BEMTOOL workflow. It is an upstream calibration step intended to improve the biological consistency of ALADYM before running management or bioeconomic scenarios. No knowledge of BEMTOOL’s economic or management scenario modules is required to apply the tuning, in that only ALADYM parameters are tuned.
The approach is a structured grid search: no optimisation algorithm is employed. The procedure is diagnostic and comparative, not predictive.
For a full description of BEMTOOL structure, data requirements, and installation, refer to the official tutorial: BEMTOOL Tutorial.
Installation of BEMTOOL and ALADYM must be completed following that guide before attempting any tuning procedure described below.
How to install ALADYM tuning
Overview of the tuning workflow
The tuning process follows a fixed and sequential workflow designed to ensure consistency and reproducibility across all simulations. First, the user defines the ranges of the parameters to be explored, specifying the discrete values that will be tested during calibration. Based on these ranges, the tuning scripts automatically generate multiple ALADYM configuration files, each representing a unique parameter combination derived from the baseline setup.
ALADYM is then executed in batch mode for every generated configuration, with no manual intervention required during the simulation phase. Once all runs are completed, the relevant simulation outputs are systematically extracted and aligned with the corresponding assessment data. These simulated results are compared against observations to quantify discrepancies across time and indicators.
For each parameter combination, a numerical score is computed to summarise model performance. The combination that minimises this score is identified and stored as the best-performing solution. Finally, the tuning framework produces diagnostic plots and summary tables that allow the user to evaluate model behaviour, assess trade-offs, and verify the performance of the selected parameter set.
The tuning procedure is deliberately restricted to a defined subset of ALADYM biological parameters, ensuring that calibration targets only the processes of interest.
Figure 1 - Conceptual overview of ALADYM tuning framework.
Specifically, the tuning process is a two-stage process. In Stage 1, the biological parameters of recruitment time Tr and the age range over which fishing mortality is averaged Fbar are tuned. Once the best combination is found, this is used in Stage 2 to tune the fleet- and gear-specific selectivity parameters. This stage evaluates both stock-level and fleet-level consistency.
Note that the stages are executed sequentially, not jointly.
Tr-Fbar tuning
The Tr–Fbar tuning explores alternative combinations of the recruitment timing parameter Tr and the age range used to compute mean fishing mortality Fbar. All other biological and fleet parameters are held fixed. The goal is to identify the Tr–Fbar combination that minimises the discrepancy between ALADYM outputs and stock assessment time series.
Input data requirements
After installation of the ALADYM tuning software, a baseline ALADYM configuration must be prepared. This baseline configuration is the structural reference from which all tuning combinations are generated. Every Tr–Fbar or selectivity configuration produced by the tuning scripts is a direct modification of this baseline.
Several constraints are critical.
Natural mortality (M) files must start at age 0. Any offset in age indexing will cause silent misalignment between biological processes and assessment data, invalidating error calculations.
Missing values in all configuration files must be encoded as NAN, not NA. ALADYM is not NA-aware. Using NA leads to type coercion, failed reads, or numerical propagation of missing values - NAN is explicitly handled by the model and by the tuning scripts.
The ALADYM configuration file used here is not the same as the BEMTOOL configuration file. BEMTOOL wraps ALADYM but applies additional preprocessing and abstractions. The tuning workflow operates directly on ALADYM inputs. A template ALADYM configuration file adapted for tuning is provided here.
Finally, the simulation period defined in the configuration must match exactly the years available in the assessment time series used for calibration. No extrapolation or truncation is performed automatically.
Generation of Tr–Fbar combinations
Tr–Fbar tuning is based on a grid search approach. The parameter space is discretised into a finite set of Tr values and Fbar age ranges, and ALADYM is run once for each possible combination.
The generation of parameter combinations is handled by the script:
ALADYM_tuning_main_config.R
This script performs the following operations:
Reads the baseline ALADYM configuration file.
Defines the vectors of Tr values and Fbar age ranges to be explored.
Creates all possible Tr–Fbar combinations using a Cartesian product.
Writes a new ALADYM configuration file for each combination.
Each generated configuration file differs from the baseline only in the Tr value and the Fbar age range. All other settings are inherited unchanged. The resulting configuration files are automatically written to:
C:/INPUT/ALADYM
The naming convention encodes the Tr–Fbar combination, ensuring that each run can be uniquely identified and traced back to its parameter values.
EXAMPLE OF NAMING CONVENTION
Once this script has been executed, no further manual editing of configuration files is required.
Running the Tr–Fbar tuning
After the configuration files have been generated, the tuning itself is launched using:
ALADYM_tuning.R
This script automatically:
iterates over all Tr–Fbar configuration files,
launches ALADYM in batch mode for each configuration,
extracts annual SSB, Fbar, and total catch from the simulation outputs,
computes relative errors with respect to assessment data,
calculates a scalar score for each combination as the sum of mean squared relative errors,
stores results in a cumulative calibration table.
The procedure is entirely automated. No user interaction is required while the tuning is running.
At the end of the process, the script identifies the Tr–Fbar combination with the lowest total score and records it as the best-performing configuration.
Outputs and diagnostics
For each Tr–Fbar combination, ALADYM outputs are saved in a dedicated folder named after the parameter combination. These folders contain the extracted annual time series used for calibration.
** ADD EXAMPLE FOLDER NAME **
In addition, the tuning script produces:
a summary table of errors and scores for all combinations,
diagnostic plots comparing simulations to assessment data,
highlighted plots for the best-performing Tr–Fbar combination.
These outputs allow both quantitative comparison and visual inspection of model behaviour across the explored parameter space.
This concludes the Tr–Fbar tuning stage. Subsequent tuning steps, such as selectivity calibration, build directly on the optimal Tr–Fbar configuration identified here.
Selectivity tuning
Selectivity tuning is performed only after the Tr–Fbar tuning stage has converged. The optimal Tr–Fbar combination is treated as fixed input. Selectivity tuning explores alternative gear-specific selectivity parameterisations while holding recruitment timing, fishing mortality structure, and all biological parameters constant.
This is a controlled second-stage calibration. The objective is to improve fleet-specific catch dynamics without destabilising stock-level indicators.
Input data requirements
Selectivity is defined at the fleet-segment level. Each fleet is associated with:
a selectivity type identifier,
a fixed number of parameter slots (six in the input file),
a subset of those parameters actually used, depending on the selectivity type.
The selectivity input file is rectangular by design: all fleets share the same column structure, even if some parameters are unused. Unused parameters must still be present and must be left empty.
Definition of parameter ranges
Selectivity tuning is driven by user-defined parameter ranges. For each parameter involved in a given selectivity type, a discrete set of candidate values is specified.
These ranges are defined in R as simple numeric vectors. The tuning scripts do not assume continuity or bounds; they only enumerate combinations.
Only parameters that are active for a given selectivity type are included in the combination space. The remaining parameter slots are left unchanged from the baseline configuration.
Generation of selectivity configurations
Configuration generation is handled by the selectivity tuning scripts. Internally, the process follows three steps:
The selectivity file is split by fleet segment.
For each fleet, all valid parameter combinations are generated using a Cartesian product over the active parameters.
Full-model configurations are created by combining fleet-level parameter choices across fleets.
The result is a set of complete ALADYM configurations, each corresponding to one unique multi-fleet selectivity setup. Each configuration modifies only the selectivity file; all other inputs remain identical to the optimal Tr–Fbar baseline.
Configuration folders are named systematically to encode the selectivity parameter combination. This naming is later used to aggregate results and compute scores.
Running selectivity tuning
Once configuration files are generated, the selectivity tuning run is launched in batch mode. For each configuration, ALADYM is executed and the following outputs are extracted:
stock-level indicators (SSB, Fbar, total catch),
fleet-specific annual catches.
Relative errors are computed both at the stock level and at the fleet level. Fleet errors are retained explicitly rather than collapsed immediately, allowing inspection of trade-offs between fleets.
A global score is computed by combining stock-level errors with fleet-level error summaries. The weighting scheme is transparent and can be modified if required.
Outputs and diagnostics
Selectivity tuning produces:
a comprehensive error table with one row per configuration,
fleet-specific error metrics,
diagnostic plots showing simulated versus observed catches for each fleet,
aggregated plots showing all selectivity simulations against observations.
The best-performing configuration is identified based on the defined score criterion, but alternative near-optimal solutions can be inspected to evaluate robustness and fleet trade-offs.